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(57) Propagation of a command status code from a 
remote unit to a host unit. A command to be executed 
on a remote unit is passed from a host unit to the remote 
unit, using a remote command execution facility, such 
as the remote shell (RSH) facility of UNIX. The com- 
mand is executed on the remote un it and the status code 
of the command is forwarded from the remote unit to the 
host unit, using the remote command execution facility. 
In one example, the status code is appended to stand- 
ard output, so that it can be retrieved and used in further 
processing. 
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Description 

[0001] This invention relates, in general, to the remote 
execution of commands and, in particular, to the receipt 
at a host unit of the status of a command executed on s 
a remote unit. 

[0002] This application contains subject matter which 
is related to the subject matter of the following United 
States applications, which are assigned to the same as- 
signee as this application and filed on the same day as 
this application. The below listed applications are here- 
by incorporated herein by reference in their entirety: 

"Method Of Propagating A Command Status Code 
From A Remote Unit To A Host Unit, - by Richard C. 
Russell, Serial No. 08/892,782, (Docket No. 
PO9-97-012); and 

"Propagation Of A Command Status Code From A 
Remote Unit To A Host Unit," by Richard C. Russell, 

Serial No. , (Docket No. 

PO9-97-083). 

[0003] Within many computer environments, multiple 
processors are connected to one another using typical 
telecommunications connections, such as TCP/l P or to- 
ken rings. 

[0004] I n these environments, there is often a need or 
desire to execute a command on one processor, when 
logged onto another processor. That is, there is a need 
or desire to execute the command remotely. 
[0005] In, for instance, UNIX-based operating sys- 
tems, a command can be executed remotely using a re- 
mote shell (RSH) facility. Often, the remote shell facility 
is invoked from within a shell script that includes one or 
more statements. When the shell script is run, each 
statement is executed one at a time. 
[0006] When the shell script invokes the RSH facility, 
the RSH facility causes a specified command to be ex- 
ecuted at a specified network-connected remote proc- 
essor. That is, the specified command is run on the re- 
mote processor via RSH and the results of the specified 
command are returned back to the host processor (i.e., 
the processor issuing the request). The results include 
"standard output", which is the output of the specified 
command, and "standard error", which includes any er- 
ror messages that were generated by the command. 
However, neither "standard output" nor "standard error" 
includes the status code (e.g., the return code or the exit 
code) of the executed specified command. 
[0007] In particular, when the specified command is 
executed remotely, it generates a status code. However, 
RSH is incapable of returning the status code to the host 
processor. Instead, the status code of the specified com- 
mand is lost and/or disregarded, and what is returned is 
the status condition of the RSH facility. 
[0008] Since the status code of the specified com- 
mand is not returned to the host processor, further 



processing to take place after execution of the specified 
command (e.g., processing within the script) is tenuous, 
at best. This is due to the uncertainty of whether the 
specified command executed successfully or not. 
[0009] Based on the foregoing, a need exists for a ca- 
pability that enables the return of the status code of a 
remotely executed command, when the command is ex- 
ecuted using a facility, such as RSH. 
[001 0\ The shortcomings of the prior art are overcome 
and additional advantages are provided through the pro- 
vision of a system of propagating a status code from a 
remote unit to a host unit. A host unit is adapted to pass 
from the host unit to a remote unit a command to be 
executed on the remote unit. 

[0011] The host unit uses a remote command execu- 
tion facility. The remote unit is adapted to execute the 
command, and to forward a status code of the command 
from the remote unit to the host unit. The remote unit 
also uses the remote command execution facility to for- 
ward the status code. 

[0012] In one embodiment, the host unit is further 
adapted to issue a remote command execution facility 
invocation to execute the command on the remote unit. 
The remote command execution facility invocation iden- 
tifies the command. 

[001 3] In a further embodiment, the remote command 
execution facility invocation is issued from within a sub- 
routine, and the subroutine is called from within a shell 
script or a computer program. 

[0014] In yet a further embodiment, the remote unit is 
further adapted to run another command on the remote 
unit. The another command is identified on the remote 
command execution facility invocation, and the execu- 
tion of the first command is under control of the another 
command. 

[0015] In another embodiment of the present inven- 
tion, the remote unit is further adapted to include the 
status code in standard output generated during execu- 
tion of the command, and pass the standard output to 
the host unit. 

[0016] In another embodiment of the present inven- 
tion, a system of propagating a status code from a re- 
mote unit to a host unit is provided, which includes: 
means for invoking from within a subroutine on a host 
unit a remote command execution facility to execute a 
first command; means for executing the first command 
on a remote unit; means for executing a second com- 
mand on the remote unit via the first command; and 
means for forwarding a status code of the second com- 
mand from the first command on the remote unit to the 
host unit. 

[0017] The capabilities of the present invention ad- 
vantageously allow the return of a status code of a re- 
motely executed command, via a remote command ex- 
ecution facility, such as RSH. The capabilities of the 
present invention are easily adaptable to the scripting 
environments and do not require the changing of oper- 
ating system code. The capabilities of the present tn- 
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vention enable the return of the status code, even if no 
other output is generated or is being returned to the host 
unit. 

[0018] Additional features and advantages are real- 
ised through the techniques of the present invention. 
Other embodiments and aspects of the invention are de- 
scribed in detail herein and are considered a part of the 
claimed invention. 

[0019] The subject matter which is regarded as the 
invention is particularly pointed out and distinctly 
claimed in the claims at the conclusion of the specifica- 
tion. The foregoing and other objects, features, and ad- 
vantages of the invention will be apparent from the fol- 
lowing detailed description taken in conjunction with the 
accompanying drawings in which: 

FIG. 1 depicts one example of a computer environ- 
ment incorporating and using the status code prop- 
agation capability of the present invention; 

FIG. 2 depicts one embodiment of further details 
within the computer environment of FIG. 1 incorpo- 
rating and using the status code propagation capa- 
bility of the present invention; and 

FIG. 3 depicts one example of the logic associated 
with the status code propagation capability of the 
present invention. 

[0020] In accordance with the principles of the present 
invention, a capability is provided in which a status code 
of a remotely executed command is returned to the host 
unit (e.g., the unit requesting execution of the command) 
via a remote command execution facility. In particular, 
the remote command execution facility, which was pre- 
viously unable to return the status code, is adapted to 
allow the propagation of the status code from a remote 
unit to the host unit. 

[0021] One example of a computer environment in- 
corporating and using the status code propagation ca- 
pability of the present invention is described in detail be- 
low with reference to FIG. 1. 

[0022] Referring to FIG. 1 , in one embodiment, a com- 
puter environment 100 includes a plurality of units 102 
coupled to one another via a connection 104. In one ex- 
ample, each unit is a UNIX workstation running a UNIX- 
based operating system, and the units are coupled to 
one another via a TCP/IP connection. 
[0023] Each unit includes, for instance, a central 
processing unit, memory and one or more input/output 
devices, which are well known in the art. 
[0024] The above-described environment in which 
each unit is a UNIX workstation running a UNIX-based 
operating system is only one example, however. The 
status code propagation capability of the present inven- 
tion can be incorporated and used with any type of com- 
puters, processors, systems, workstations and/or envi- 
ronments, without departing from the spirit of the 



present invention. 

[0025] For instance, in another embodiment, one or 
more of the units is a PS/2 offered by International Busi- 
ness Machines Corporation. In a further embodiment, 

$ one or more of the units is based upon the Enterprise 
Systems Architecture offered by International Business 
Machines Corporation. Further, the operating system 
need not be UNIX-based. For example, the operating 
system can include the Multiple Virtual Storage (MVS) 

10 operating system offered by International Business Ma- 
chines Corporation. Additionally, connection 104 need 
not be TCP/IP It can be any type of wire connection, 
token ring or network connection, to name just a few 
more examples. 

is [0026] In yet a further embodiment, the environment 
includes a large parallel system with a plurality of units 
(e.g., 512 nodes) coupled to one another via a network 
connection, such as a switch. Additionally, in other en- 
vironments, the units can be of differing types connected 

20 to one another via one or more connections. The inven- 
tion is not limited to a particular number of units coupled 
together nor the type of units that are coupled. 
[0027] Again, other types of computers, processors, 
systems, workstations, and/or environments can in- 

25 elude the status code propagation capability of the 
present invention, and all of these types are considered 
within the scope of the present invention. 
[0028] In accordance with the principles of the present 
invention, at least one of units 102 is a host unit 102a, 

30 which is coupled to one or more remote units 102b. 
Commands invoked on a host unit (e.g., a local unit orig- 
inating a request) are executed on one or more of the 
remote units. For instance, if a particular management 
function is to be carried out on a number of remote units, 

35 a specified command representing the management 
function is invoked at the host unit and remotely execut- 
ed on the remote units. 

[0029] In one embodiment, the specified command is 
invoked via a remote command execution facility, the 

40 invocation of which is embedded within, for instance, a 
shell script (e.g., written in PERL) or a computer pro- 
gram (e.g., written in C) located on the host unit. 
[0030] One example of a remote command execution 
facility is the RSH facility of UNIX. RSH is described in 

4S UNIX Network Programming , by W. Richard Stevens, 
Prentice Hall, 1 990, ISBN 0-1 3-949576-1 , which is here- 
by incorporated herein by reference in its entirety. 
[0031] The remote command execution facility trans- 
ports the specified command from the host unit to the 

so remote units to be executed on the remote units and for- 
wards back to the host unit the "standard output" and 
"standard error" generated during execution of the spec- 
ified command. 

[0032] The "standard output" includes the output of 
55 the specified command, and the "standard error" in- 
cludes a list of error messages issued by the command. 
However, neither "standard output" nor "standard error" 
includes the status code (e.g., an exit or return code) of 
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the specified command. 

[0033] That is, neither "standard output" nor "stand- 
ard error" provides an indication of whether the specified 
command terminated successfully. Thus, prior to the 
present invention, the remote command execution facil- 
ity was characterised as being incapable of returning to 
the host unit the status code of the remotely executed 
specified command. 

[0034] However, in accordance with the principles of 
the present invention, the remote command execution 
facility is capable of returning the status code from the 
remote unit(s) to the host unit, as described in detail be- 
low with reference to FIGs. 2 and 3. 
[0035] Referring to FIG. 2, in one example, host unit 
1 02a includes a shell script 202 written in a scripting lan- 
guage, such as PERL Shell script 202 includes an in- 
vocation 204 of a subroutine 206. In particular, the sub- 
routine invocation includes the following syntax, as one 
example: 

$x=&runitrc-sub(remote,cmd); 
[0036] Where: 

$x is a variable to capture the status code, as de- 
scribed below; 

& denotes the invocation of a subroutine; 

runitrc-sub is the name of the subroutine; 

remote identifies the remote unit in which a speci- 
fied command is to be executed; and 

cmd identifies the specified command to be execut- 
ed on the remote unit, designated by remote. 

[0037] The shell script can include additional state- 
ments (e.g., commands and/or operations) to be per- 
formed before and/or after the subroutine invocation, as 
designated in the figure by the elipses. Additionally, a 
plurality of subroutine invocations can be included in or- 
der to execute the specified command (or other speci- 
fied commands) on a plurality of remote units. 
[0038] The code for subroutine 206 (i.e., the runitrc 
subroutine) is provided various information during the 
invocation, which include identification of the remote 
unit to execute the specified command and the specified 
command to be executed on the remote unit. 
[0039] The subroutine takes that information and is- 
sues a remote shell invocation 208 against the specified 
remote unit. This invocation, however, is an invocation 
of a runitrc command, as opposed to the specified com- 
mand. One example of the syntax for runitrc command 
invocation 208 is the following: 
@stdout='rsh remote runitrc cmd 1 ; 
[0040] Where: 

©stdout refers to a variable on the left hand side of 
an assignment (=), which is used, as described be- 



low, to capture the output of the remotely executed 
specified command; and 

' 'on the right-hand side of the assignment indicates 
5 an inline invocation of a command. In this example, 
"rsh" indicates this is a remote command execution 
facility (e.g., RSH) command to be run on the unit 
designated by "remote". The remote command ex- 
ecution facility command to be run is "runitrc cmd." 
That is, the remote command execution facility 
transports the string "runitrc cmd" to the remote unit 
and executes it on remote unit 102b. 

[0041] In particular, the command runitrc (designated 
by reference numeral 210) is run under the control of 
the remote command execution facility. The code for the 
runitrc command is located on the remote unit. The ru- 
nitrc command takes the parameter it has been supplied 
(e.g., cmd) and executes it, when it reaches inline invo- 
cation 212 of cmd. 

[0042] In one example, cmd is invoked using the fol- 
lowing syntax: 
system( , cmd , );. 

[0043] The above is a system call that executes the 
specified command inline. The output (e.g., standard 
output, standard error) of the specified command is 
merged with the output (e.g., standard output, standard 
error) of the runitrc command. 

[0044] As with the shell script, runitrc command 210 
also includes one or more various other statements (e. 
g. commands and/or operations) before and/or after the 
invocation of the specified command. In one example, 
one of the additional statements is statement 213 
"$rc=$?;\ which is used as described below to capture 
the status code of the specified command. 
[0045] Another statement is a print statement 21 4. In 
this example, the print statement writes to the "standard 
output", designated by STDOUT, the status code of the 
specified command, in accordance with the principles 
of the present invention. This is described in further de- 
tail below. 

[0046] Additionally, the runitrc command includes an 
exit statement 216, which terminates the invocation of 
the runitrc command. Thereafter, the remote command 
execution facility (e.g., RSH) returns "standard output" 
to subroutine 206, at reference numeral 208. Addition- 
ally, "standard error" is returned by the remote command 
execution facility and it is merged with "standard error* 
of the shell script. 

[0047] After the output, error messages and status 
code are returned to the subroutine, one or more other 
statements may be executed inline. In one example, a 
return statement 218 is executed, which returns the sta- 
tus code to shell script 202. The shell script is then able 
to do further processing with the status code, in accord- 
ance with the principles of the present invention. 
[0048] One example of a logic flow diagram of the 
functions included in the status code propagation capa- 
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bility of the present invention is depicted in FIG. 3 and 
described in detail below. For this discussion, reference 
is also made to FIG. 2. The reference numerals within 
the 200*s can be found in FIG. 2. 
[0049] Referring to FIG. 3, initially, a subroutine (e.g., 
the runitrc subroutine) is invoked in order to have a spec- 
ified command (designated by cmd) executed on a re- 
mote unit, STEP 300. In one example, subroutine 206 
is a library routine invoked from within shell script 202 
using invocation 204. In another embodiment, however, 
the subroutine is invoked from within a computer pro- 
gram, such as a program written in C. 
[0050] Thereafter, a remote command execution fa- 
cility (e.g., RSH) invocation is issued from within the 
subroutine in order to execute a runitrc command on a 
remote unit, which in turn will remotely execute the spec- 
ified command (cmd), STEP 302. In one instance, the 
remote command execution facility is invoked by invo- 
cation 208, as described above. 
[0051] In particular, the remote command execution 
facility (e.g., RSH) transports the string 'runitrc cmd" to 
the remote unit designated by "remote". 
[0052] The command, runitrc, is then run on the re- 
mote unit under the control of the remote command ex- 
ecution facility, STEP 304. Specifically, the statements 
within the runitrc conunand are executed inline, one at 
a time. At a particular point within the code for the runitrc 
command, an invocation is reached for the specified 
command to be executed on the remote unit. In one ex- 
ample, the specified command, designated by cmd, is 
invoked by invocation 212. It should be noted that cmd 
represents a string of one or more words that identify 
the specified command to be remotely executed. 
[0053] The specified command is then executed, 
STEP 306, and the output of the specified command, if 
any, is captured in "standard output" and the error mes- 
sages, if any, are captured in "standard error". Addition- 
ally, in accordance with the principles of the present in- 
vention, the status code of the specified command is 
captured, STEP 308. In one example, the status code 
is captured using the following assignment: 
$rc=$?: 

[0054] Where: 

$rc is the variable to contain the status code; and 

$? is a variable that contains the status code of the 
most recently executed command (i.e., the speci- 
fied command, in this instance). 

[0055] Thereafter, the status code (e.g., the value of 
$rc) is written to "standard output", using print statement 
214 within the runitrc command code. One embodiment 
of the syntax of the print statement is as follows: 
print(stdout "»>The status code from the command 
was: $rc");. 

[0056] In particular, the status code of the specified 
command is captured within the variable $rc and a spe- 



cial text string "»>The status code from the command 
was:" is added to the already provided "standard output" 
text. That is, in one example, this special text line is add- 
ed to the last line of "standard output". If there is no out- 
5 put, then this special text line will be the only line within 
"standard output". 

[0057] Thereafter, invocation of the runitrc command 
is terminated, when, for instance, exit statement 216 
within the runitrc command is reached, STEP 310. After 
10 completion of the runitrc command, the status code is 
returned to the calling subroutine 206, the runitrc sub- 
routine, via the remote command execution facility. In 
particular, the remote command execution facility for- 
wards to the calling subroutine the "standard output", 
which now includes the status code of the specified 
command. Additionally, "standard error" is returned. 
The manner in which "standard output" and "standard 
error" are forwarded from a remote unit to a host unit is 
known to those skilled in the art. 
[0058] "Standard output", including the status code 
line, is returned within the runitrc subroutine to the var- 
iable ©stdout (reference numeral 208). Subsequently, 
other processing within the subroutine can take place. 
For instance, a determination is made as to whether the 
status code is available, STEP 31 4. In particular, the last 
line of "standard output" is stripped off and the subrou- 
tine code looks for the numeric value following the text 
string "»> The status code from the command was:". 
If, for some reason, the status code is not returned, an 
error message is passed to the invoker of the subroutine 
(e.g., shell script 202), STEP 316. 
[0059] If, however, the status code is returned, the 
status code is provided to the invoker of the subroutine, 
STEP 318. In one example, the status code is returned 
to the shell script using the statement, return $rc (refer- 
ence numeral 218). 

[0060] The status code is returned to the shell script 
into the variable $x in invocation 204. At this time, the 
code of the shell script can take further action. For in- 
stance, conditional logic can be included in order to per- 
form further tasks depending on the value of the status 
code. 

[0061] In the above example, the status code is added 
to the last line of "standard output". This is only one ex- 
ample, however. In another embodiment, the status 
code can be added to other places within "standard out- 
put". In yet a further embodiment, the status code can 
be returned with "standard error". 
[0062] In one example of the present invention, the 
status code is returned in the "standard output", even if 
the coder of the remote specified command indicates 
that no output is to be generated. 
[0063] In accordance with the principles of the present 
invention, the remote command execution facility is pro- 
vided with the ability to return a status code of a remotely 
executed command from a remote unit to a host unit. 
This advantageously allows the calling script or program 
to perform certain other tasks, which depend on the 
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proper return of the status code. The present invention 
provides an easy mechanism for interactive shell script- 
ing environments executing remote command execu- 
tion facilities to receive accurate status codes from re- 
motely executed commands. With the present inven- 
tion, the operating system code (e.g., the UNIX operat- 
ing system code) need not be changed. 
[0064] In accordance with the principles of the present 
invention, the command can be sent from a host unit to 
a plurality of remote units. Each of the remote units 
would include the runitrc command code, in this exam- 
ple. A status code would then be returned from each of 
the remote units. In a further embodiment, multiple host 
units can be used to send commands to one or more 
remote units. 

[0065] The present invention can be included in an ar- 
ticle of manufacture (e.g., one or more computer pro- 
gram products) having, for instance, computer useable 
media. 

[0066] The media has embodied therein, for instance, 
computer readable program code means for providing 
and facilitating the capabilities of the present invention. 
The article of manufacture can be included as a part of 
a computer system or sold separately. 
[0067] The flow diagrams depicted herein are just ex- 
emplary. There may be many variations to these dia- 
grams or the steps (or operations) described therein 
without departing from the spirit of the invention. For in- 
stance, the steps may be performed in a differing order, 
or steps may be added, deleted or modified. All of these 
variations are considered a part of the claimed inven- 
tion. 

[0068] The present invention also relates to a system 
of propagating a status code from a remote un it to a host 
unit, said system comprising: 

means for invoking from within a subroutine on a 
host unit a remote command execution facility to ex- 
ecute a first command; 

means for executing said first command on a re- 
mote unit; 

means for executing a second command on said 
remote unit via said first command; and 

means for forwarding a status code of said second 
command from said first command on the remote 
unit to said host unit. 

[0069] The system of the previous paragraph further 
comprises either a) means for invoking said subroutine 
from within either a shell script or a computer program; 
or 



first command; 

means for exiting said first command; and 

s means for passing said standard output from said 
remote unit to said host unit using said remote com- 
mand execution facility. 

[0070] Although preferred embodiments have been 
10 depicted and described in detail herein, it will be appar- 
ent to those skilled in the relevant art that various mod- 
ifications, additions, substitutions and the like can be 
made without departing from the invention as defined in 
the following claims. 



Claims 

1. A system of propagating a status code from a re- 
20 mote unit (102) to a host unit (102a), said system 
comprising: 

a host unit adapted to pass from the host unit 
to a remote unit a command (300) to be exe- 
25 cuted on said remote unit, said host unit using 

a remote command execution facility (302); and 

said remote unit being adapted to execute said 
command and to forward a status code (318) 
30 of said command from said remote unit to said 

host unit, said remote unit using said remote 
command execution facility to forward said sta- 
tus code. 

35 2. The system of claim 1 , wherein said remote com- 
mand execution facility being incapable of returning 
said status code from said remote unit is enabled 
to return said status code. 

40 3. The system of claim 1 , wherein said host unit is fur- 
ther adapted to issue a remote command execution 
facility invocation to execute said command on said 
remote unit, said remote command execution facil- 
ity invocation identifying said command. 

45 

4. The system of claim 3, wherein said remote com- 
mand execution facility invocation is issued from 
within a subroutine (302), said subroutine being 
called from within either a shell script or a computer 

so program. 

5. The system of claim 3, wherein said remote unit is 
further adapted to run another command (306) on 
said remote unit, said another command being 
identified on said remote command execution facil- 
ity invocation, and wherein execution of said com- 
mand is under control of said another command. 



b) means for adding said status code to standard 
output generated for said second command, said 
adding being performed during execution of said 
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6. The system of claim 5, wherein said remote unit is 
further adapted to pass said status code of said 
command from said another command to said host 
unit using capabilities of the remote command ex- 
ecution facility. 5 

7. The system of claim 1 , wherein said remote unit is 
further adapted to: 

include said status code in standard output 10 
generated during execution of said command; 
and 



pass said standard output to said host unit. 

The system of claim 7, further comprising means 
for removing said status code from said standard 
output. 
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(57) Propagation of a command status code from a 
remote unit to a host unit. A command to be executed 
on a remote unit is passed from a host unit to the remote 
unit, using a remote command execution facility, such 
as the remote shell (RSH) facility of UNIX. The com- 
mand is executed on the remote unit and the status code 
of the command is forwarded from the remote unit to the 
host unit, using the remote command execution facility. 
In one example, the status code is appended to stand- 
ard output, so that it can be retrieved and used in further 
processing. 
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